package com.sunday.common.doc;

import com.sunday.common.core.remoting.rest.response.RestResponse;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.enums.ParameterIn;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

/**
 * 在 Swagger/OpenAPI 3 中，io.swagger.v3.oas.annotations.enums.ParameterIn 的不同枚举值用于指定参数的位置。
 * DEFAULT：通常对应请求体中的参数。在实际使用中，并不常见直接使用 DEFAULT，更多是通过 @RequestBody 等注解来表示请求体参数，没有明确的特定字面意义上的 “默认位置” 的统一理解。
 * HEADER：表示参数在 HTTP 请求的头部。例如，常见的 Authorization 头部字段可以通过将参数位置设置为 HEADER 来描述和文档化。
 * QUERY：代表参数在 URL 的查询字符串中。比如在 https://example.com/api?param1=value1 中，param1 就是一个查询参数，其位置可以用 QUERY 来表示。
 * PATH：表示参数是 URL 路径的一部分。例如在 /users/{userId} 中，userId 就是路径参数，其位置用 PATH 来表示。
 * COOKIE：表示参数在 HTTP 请求的 Cookie 中。某些场景下可能会从 Cookie 中获取特定的参数值，这时就可以用 COOKIE 来指定参数位置。
 */
@RestController
@Tag(name = "示例控制器", description = "提供一些示例 API")
public class ExampleController {

    @GetMapping("/hello/{name}")
    @Operation(summary = "打招呼的 API", description = "根据提供的名字返回问候语")
    public ResponseEntity<String> sayHello(@PathVariable("name") @Parameter(description = "要打招呼的人的名字") String name) {
        return ResponseEntity.ok("Hello, " + name + "!");
    }

    /**
     * @Description: 新增 权限表 数据
     * @Param: [savePermissionsReqVO]
     * @Return: com.sunday.common.core.remoting.rest.response.RestResponse
     * @author: zsy
     * @Create: 2024/09/22 16:24:39
     */
    @Operation(summary = "新增", description = "新增 权限表 数据")
    @PostMapping("/save")
    public RestResponse<?> save(
//            @Parameter(description = "新增 权限VO", in = ParameterIn.DEFAULT)
            @RequestBody SavePermissionsReqVO savePermissionsReqVO) {
        return RestResponse.ok();
    }

    /**
     * @param saveBatchPermissionsReqVO
     * @return
     * @Description: 权限表 批量权限保存
     */
    @Operation(summary = "批量权限保存", description = "权限表 批量权限保存")
    @PostMapping("/saveBatch")
    public RestResponse<?> saveBatch(
//            @Parameter(description = "批量 权限VO", in = ParameterIn.DEFAULT)
            @RequestBody SaveBatchPermissionsReqVO saveBatchPermissionsReqVO) {
        return RestResponse.ok();
    }


}